package com.zenithmind.document.service;

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.service.IService;
import com.zenithmind.document.pojo.domain.DocumentRating;
import com.zenithmind.document.pojo.dto.DocumentRatingCreateDTO;
import com.zenithmind.document.pojo.dto.DocumentRatingUpdateDTO;
import com.zenithmind.document.pojo.query.DocumentRatingQueryDTO;
import com.zenithmind.document.pojo.vo.DocumentRatingVO;

import java.util.List;

/**
 * 文档评分服务接口
 * 遵循接口隔离原则：专注于评分管理功能
 * 遵循单一职责原则：只负责评分相关操作
 * 
 * @author ZenithMind Team
 * @since 2025-01-09
 */
public interface DocumentRatingService extends IService<DocumentRating> {

    /**
     * 创建评分
     * 
     * @param createDTO 评分信息
     * @return 评分记录
     */
    DocumentRatingVO createRating(DocumentRatingCreateDTO createDTO);

    /**
     * 更新评分
     * 
     * @param id 评分ID
     * @param updateDTO 更新信息
     * @return 是否成功
     */
    Boolean updateRating(String id, DocumentRatingUpdateDTO updateDTO);

    /**
     * 删除评分
     * 
     * @param id 评分ID
     * @return 是否成功
     */
    Boolean deleteRating(String id);

    /**
     * 批量删除评分
     * 
     * @param ids 评分ID列表
     * @return 是否成功
     */
    Boolean batchDeleteRatings(List<String> ids);

    /**
     * 分页查询评分
     * 
     * @param queryDTO 查询条件
     * @return 分页结果
     */
    IPage<DocumentRatingVO> getRatingPage(DocumentRatingQueryDTO queryDTO);

    /**
     * 获取评分详情
     * 
     * @param id 评分ID
     * @return 评分详情
     */
    DocumentRatingVO getRatingDetail(String id);

    /**
     * 获取文档评分列表
     * 
     * @param documentId 文档ID
     * @param limit 限制数量
     * @return 评分列表
     */
    List<DocumentRatingVO> getDocumentRatings(String documentId, Integer limit);

    /**
     * 获取用户评分列表
     * 
     * @param userId 用户ID
     * @param limit 限制数量
     * @return 评分列表
     */
    List<DocumentRatingVO> getUserRatings(String userId, Integer limit);

    /**
     * 获取文档平均评分
     * 
     * @param documentId 文档ID
     * @return 平均评分
     */
    Double getDocumentAverageRating(String documentId);

    /**
     * 获取文档评分统计
     * 
     * @param documentId 文档ID
     * @return 评分统计
     */
    Object getDocumentRatingStatistics(String documentId);

    /**
     * 检查用户是否已评分
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @return 是否已评分
     */
    Boolean hasUserRated(String documentId, String userId);

    /**
     * 获取用户对文档的评分
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @return 用户评分
     */
    DocumentRatingVO getUserDocumentRating(String documentId, String userId);

    /**
     * 用户评分文档
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @param rating 评分
     * @param comment 评论
     * @return 评分记录
     */
    DocumentRatingVO rateDocument(String documentId, String userId, Double rating, String comment);

    /**
     * 更新用户评分
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @param rating 新评分
     * @param comment 新评论
     * @return 是否成功
     */
    Boolean updateUserRating(String documentId, String userId, Double rating, String comment);

    /**
     * 取消用户评分
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @return 是否成功
     */
    Boolean cancelUserRating(String documentId, String userId);

    /**
     * 获取评分分布
     * 
     * @param documentId 文档ID
     * @return 评分分布
     */
    List<Object> getRatingDistribution(String documentId);

    /**
     * 获取热门评分文档
     * 
     * @param limit 限制数量
     * @return 文档列表
     */
    List<Object> getTopRatedDocuments(Integer limit);

    /**
     * 获取最新评分
     * 
     * @param limit 限制数量
     * @return 评分列表
     */
    List<DocumentRatingVO> getLatestRatings(Integer limit);

    /**
     * 获取评分趋势
     * 
     * @param documentId 文档ID
     * @param days 统计天数
     * @return 趋势数据
     */
    List<Object> getRatingTrend(String documentId, Integer days);

    /**
     * 搜索评分
     * 
     * @param keyword 关键词
     * @param limit 限制数量
     * @return 评分列表
     */
    List<DocumentRatingVO> searchRatings(String keyword, Integer limit);

    /**
     * 获取评分评论
     * 
     * @param documentId 文档ID
     * @param hasComment 是否有评论
     * @param limit 限制数量
     * @return 评分列表
     */
    List<DocumentRatingVO> getRatingComments(String documentId, Boolean hasComment, Integer limit);

    /**
     * 点赞评分
     * 
     * @param ratingId 评分ID
     * @param userId 用户ID
     * @return 是否成功
     */
    Boolean likeRating(String ratingId, String userId);

    /**
     * 取消点赞评分
     * 
     * @param ratingId 评分ID
     * @param userId 用户ID
     * @return 是否成功
     */
    Boolean unlikeRating(String ratingId, String userId);

    /**
     * 举报评分
     * 
     * @param ratingId 评分ID
     * @param userId 用户ID
     * @param reason 举报原因
     * @return 是否成功
     */
    Boolean reportRating(String ratingId, String userId, String reason);

    /**
     * 审核评分
     * 
     * @param ratingId 评分ID
     * @param status 审核状态
     * @param reviewerId 审核人ID
     * @return 是否成功
     */
    Boolean reviewRating(String ratingId, Integer status, String reviewerId);

    /**
     * 批量审核评分
     * 
     * @param ratingIds 评分ID列表
     * @param status 审核状态
     * @param reviewerId 审核人ID
     * @return 是否成功
     */
    Boolean batchReviewRatings(List<String> ratingIds, Integer status, String reviewerId);

    /**
     * 获取待审核评分
     * 
     * @param limit 限制数量
     * @return 评分列表
     */
    List<DocumentRatingVO> getPendingReviewRatings(Integer limit);

    /**
     * 导出评分数据
     * 
     * @param queryDTO 查询条件
     * @return 导出数据
     */
    Object exportRatings(DocumentRatingQueryDTO queryDTO);

    /**
     * 同步评分统计
     * 
     * @param documentId 文档ID
     * @return 是否成功
     */
    Boolean syncRatingStatistics(String documentId);

    /**
     * 清理垃圾评分
     * 
     * @return 清理数量
     */
    Integer cleanupSpamRatings();

    /**
     * 获取评分质量分析
     * 
     * @param documentId 文档ID
     * @return 质量分析
     */
    Object getRatingQualityAnalysis(String documentId);

    /**
     * 获取用户评分行为分析
     * 
     * @param userId 用户ID
     * @return 行为分析
     */
    Object getUserRatingBehavior(String userId);

    /**
     * 推荐相似评分文档
     * 
     * @param documentId 文档ID
     * @param limit 限制数量
     * @return 文档列表
     */
    List<Object> recommendSimilarRatedDocuments(String documentId, Integer limit);

    /**
     * 获取评分标签统计
     * 
     * @param documentId 文档ID
     * @return 标签统计
     */
    List<Object> getRatingTagStatistics(String documentId);

    /**
     * 批量导入评分
     * 
     * @param ratings 评分数据
     * @return 导入数量
     */
    Integer batchImportRatings(List<DocumentRatingCreateDTO> ratings);
}
